﻿namespace Lite.Common
{
    /// <summary>
    /// A generic interface for types that can be started, halted, paused and
    /// restarted.
    /// </summary>
    /// <remarks>
    /// <para>
    /// A class that implements this interface should be capable of moving
    /// from a started state to a stopped state and back an indefinite number
    /// of times. Halting is not equivalent to Disposing - the instance is
    /// still accessible and potentially restartable.
    /// Equally, an instance should be able to move from the Started state to
    /// the Paused state and back again freely.
    /// </para>
    /// <para>
    /// Note that some objects will automatically enter the Paused state after
    /// completing a certain amount of work and wait for a Restart before
    /// continuing.
    /// </para>
    /// </remarks>
    public interface IStartHaltPauseRestart
        : IStartHalt
    {
        /// <summary>
        /// Move the instance from the Started state into the Paused state.
        /// </summary>
        /// <remarks>
        /// This method is only valid for objects in the Started or Paused
        /// states.
        /// </remarks>
        /// <exception cref="InvalidOperationException">
        /// The instance is not in the Started or Paused states.
        /// </exception>
        void Pause();

        /// <summary>
        /// Move the instance from the Paused state into the Started state.
        /// </summary>
        /// <remarks>
        /// <para>
        /// This method is only valid for objects in the Started or Paused
        /// states.
        /// </para>
        /// <para>
        /// Again, I wanted to call this resume. See the remarks for
        /// <see cref="Lite.Common.IStartHalt.Halt()"/>
        /// </para>
        /// </remarks>
        /// <exception cref="InvalidOperationException">
        /// The instance is not in the Started or Paused states.
        /// </exception>
        void Restart();
    }
}
